/*
DigitalFlipbook Source Code License Agreement
Copyright(c) 2008 DigitalFlipbook. All rights reserved.
	
Please read this Source Code License Agreement carefully before using
the source code.
	
DigitalFlipbook grants to you a perpetual, worldwide, non-exclusive,
no-charge, royalty-free, irrevocable copyright license, to reproduce,
prepare derivative works of, publicly display, publicly perform, and
distribute this source code and such derivative works in source or
object code form without any attribution requirements.
	
The name "DigitalFlipbook" must not be used to endorse or promote products
derived from the source code without prior written permission.
	
You agree to indemnify, hold harmless and defend DigitalFlipbook from and
against any loss, damage, claims or lawsuits, including attorney's
fees that arise or result from your use or distribution of the source
code.
	
THIS SOURCE CODE IS PROVIDED "AS IS" AND "WITH ALL FAULTS", WITHOUT
ANY TECHNICAL SUPPORT OR ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. ALSO, THERE IS NO WARRANTY OF
NON-INFRINGEMENT, TITLE OR QUIET ENJOYMENT. IN NO EVENT SHALL DIGITALFLIPBOOK
OR ITS SUPPLIERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOURCE CODE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

package com.digitalflipbook.webapis.scribd.methodgroups
{
	import com.digitalflipbook.webapis.scribd.Access;
	import com.digitalflipbook.webapis.scribd.License;
	import com.digitalflipbook.webapis.scribd.NameValuePair;
	import com.digitalflipbook.webapis.scribd.ScribdService;
	import com.digitalflipbook.webapis.scribd.ShowAds;
	import com.digitalflipbook.webapis.scribd.events.ScribdResultEvent;
	
	import flash.events.DataEvent;
	import flash.events.Event;
	import flash.net.FileReference;
	import flash.net.URLLoader;
	
	/**
	 * Broadcast as a result of the changeSettings method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_changeSettings_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #changeSettings
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="changeSettings", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_CHANGE_SETTINGS" )]
	
	/**
	 * Broadcast as a result of the delete method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_delete_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #delete
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="delete", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_DELETE" )]
	
	/**
	 * Broadcast as a result of the getConversionStatus method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_getConversionStatus_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #getConversionStatus
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="getConversionStatus", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_GET_CONVERSION_STATUS" )]
	
	/**
	 * Broadcast as a result of the getList method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_getList_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #getList
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="getList", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_GET_LIST" )]
	
	/**
	 * Broadcast as a result of the getSettings method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_getSettings_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #getSettings
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="getSettings", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_GET_SETTINGS" )]
	
	/**
	 * Broadcast as a result of the search method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_search_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #search
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="search", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_SEARCH" )]
	
	/**
	 * Broadcast as a result of the upload method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_upload_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #upload
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="upload", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_UPLOAD" )]
	
	/**
	 * Broadcast as a result of the uploadFromUrl method being called
	 *
	 * The event contains the following properties
	 *	success	- Boolean indicating if the call was successful or not
	 *	data - When success is true, contains a "docs_uploadFromUrl_response" string
	 *		   When success is false, contains an "error" ScribdError instance
	 *
	 * @see #uploadFromUrl
	 * @see com.digitalflipbook.service.scribd.ScribdError
	 * @langversion ActionScript 3.0
	 * @playerversion Flash 9.0
	 * @tiptext
	 */
	[Event( name="uploadFromUrl", 
		 type="com.digitalflipbook.webapis.scribd.events.ScribdResultEvent.DOCS_UPLOAD_FROM_URL" )]
	
	public class Docs
	{
		/** 
		 * A reference to the ScribdService that contains the api key
		 * and logic for processing API calls/responses
		 */
		private var _service:ScribdService;
		
		public function Docs( service:ScribdService )
		{
			_service = service;
		}
		
		/**
		 * This method updates the meta-data for existing documents.
		 * Only send arguments for fields you would like to overwrite.
		 * Will return a blank response object if succesful.
		 * 
		 * @param doc_ids A list of document IDs corresponding to documents to be updated.
		 * 				You can of course pass just one document ID here, in which case it will do a single update.
		 * 				But you can also pass a comma-separated list (no spaces) to do a bulk update.
		 * @param title 
		 * @param description 
		 * @param access Default: "public".
		 * @param license Default: "by-nc". See Wikipedia:Creative_Commons_License. "c" is traditional copyright. "pd" is public domain.
		 * @param show_ads This determines whether ads will be shown on this document.
		 * 				A "default" setting means that whether to show ads or not is being determined by global account settings accessible from your account page.
		 * 				Unless you want to show ads on only some documents, it is easiest to control this setting from your account page.
		 * @param tags Tags cannot contain whitespace.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.changeSettings
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function changeSettings( doc_ids:String, title:String=null, description:String=null, access:String=Access.PUBLIC, license:String=License.BY_NC, show_ads:String=ShowAds.DEFAULT, tags:String=null ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, changeSettings_result,
									"docs.changeSettings",
									true,
									new NameValuePair( "doc_ids", doc_ids ),
									new NameValuePair( "title", title ),
									new NameValuePair( "description", description ),
									new NameValuePair( "access", access ),
									new NameValuePair( "license", license ),
									new NameValuePair( "show_ads", show_ads ),
									new NameValuePair( "tags", tags ) );
		}
		
		/**
		 * Capture the result of the changeSettings call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function changeSettings_result( event:flash.events.Event ):void
		{
			// Create a DOCS_CHANGE_SETTINGS event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_CHANGE_SETTINGS );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_changeSettings_response",
												  MethodGroupHelper.parseDocsChangeSettings );
		}
		
		/**
		 * This method deletes an existing document.
		 * Will return a blank response object if succesful.
		 * 
		 * @param doc_id The document ID corresponding to the document to be deleted.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.delete
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function deleteDoc( doc_id:String ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, deleteDoc_result,
									"docs.delete",
									true,
									new NameValuePair( "doc_id", doc_id ) );
		}
		
		/**
		 * Capture the result of the delete call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function deleteDoc_result( event:flash.events.Event ):void
		{
			// Create a DOCS_DELETE event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_DELETE );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_delete_response",
												  MethodGroupHelper.parseDocsDelete );
		}
		
		/**
		 * This method retrieves the conversion status of the document.
		 * 
		 * @param doc_id The document ID corresponding to the document to retrieve the conversion status on.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.getConversionStatus
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function getConversionStatus( doc_id:String ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, getConversionStatus_result,
									"docs.getConversionStatus",
									true,
									new NameValuePair( "doc_id", doc_id ) );
		}
		
		/**
		 * Capture the result of the getConversionStatus call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function getConversionStatus_result( event:flash.events.Event ):void
		{
			// Create a DOCS_GET_CONVERSION_STATUS event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_GET_CONVERSION_STATUS );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_getConversionStatus_response",
												  MethodGroupHelper.parseDocsGetConversionStatus );
		}
		
		/**
		 * This method retrieves a list of documents for a given user.
		 * 
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.getList
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function getList():void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, getList_result,
									"docs.getList",
									true );
		}
		
		/**
		 * Capture the result of the getList call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function getList_result( event:flash.events.Event ):void
		{
			// Create a DOCS_GET_LIST event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_GET_LIST );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_getList_response",
												  MethodGroupHelper.parseDocsGetList );
		}
		
		/**
		 * This method retrieves the meta-data for existing documents.
		 * 
		 * @param doc_id The document ID corresponding to the document to retrieve the settings on.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.getSettings
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function getSettings( doc_id:String ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, getSettings_result,
									"docs.getSettings",
									true,
									new NameValuePair( "doc_id", doc_id ) );
		}
		
		/**
		 * Capture the result of the getSettings call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function getSettings_result( event:flash.events.Event ):void
		{
			// Create a DOCS_GET_SETTINGS event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_GET_SETTINGS );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_getSettings_response",
												  MethodGroupHelper.parseDocsGetSettings );
		}
		
		/**
		 * This method searches for the specified query within the scribd documents.
		 * 
		 * @param num_results Number of results to return: Default 10, max 1000.
		 * @param num_start Number to start at: Default 1. Cannot exceed 1000.
		 * @param scope Whether to search all of scribd OR just within one user/'s documents.
		 * 				If scope is set to "user" and session_key is not provided, the documents uploaded by the API user will be searched.
		 * 				If scope is set to "user" and session_key is given, the documents uploaded by the session user will be searched.
		 * 				If scope is "all", only public documents will be searched. Set to "user" by default.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.search
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function search( query:String, num_results:int=10, num_start:int=1, scope:String="user" ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, search_result,
									"docs.search",
									true,
									new NameValuePair( "query", query ),
									new NameValuePair( "num_results", num_results.toString() ),
									new NameValuePair( "num_start", num_start.toString() ),
									new NameValuePair( "scope", scope ) );
		}
		
		/**
		 * Capture the result of the search call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function search_result( event:flash.events.Event ):void
		{
			// Create a DOCS_SEARCH event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_SEARCH );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_search_response",
												  MethodGroupHelper.parseDocsSearch );
		}
		
		/**
		 * This method accepts the document file via Multi-Part POST.
		 * 
		 * @param file The contents of the file to upload. This needs to be expressed as part of a multi-part HTTP POST.
		 * @param doc_type Identify the document type with what the extension *would* be for this file. "pdf", "doc", "txt", "ppt", etc.
		 * @param access Default: "public".
		 * @param rev_id The doc_id to save uploaded file as a revision.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.upload
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function upload( file:FileReference, doc_type:String=null, access:String=Access.PUBLIC, rev_id:int=0 ):void
		{
			var fileArg:NameValuePair = new NameValuePair( "file", file.name );
			fileArg.data = file;
			
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, upload_result,
									"docs.upload",
									true,
									fileArg,
									new NameValuePair( "doc_type", doc_type ),
									new NameValuePair( "access", access ),
									new NameValuePair( "rev_id", ( rev_id == 0 ? "" : rev_id.toString() ) ) );
		}
		
		/**
		 * Capture the result of the upload call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The uploadCompleteData event generated by the FileReference
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function upload_result( event:DataEvent ):void
		{
			// Create a DOCS_UPLOAD event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_UPLOAD );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  event.data, 
												  result,
												  "docs_upload_response",
												  MethodGroupHelper.parseDocsUpload );
		}
		
		/**
		 * This method retrieves the document file from the specified URL.
		 * 
		 * @param url The url of the file to upload.
		 * @param doc_type Identify the document type with what the extension *would* be for this file. "pdf", "doc", "txt", "ppt", etc.
		 * @param access Default: "public".
		 * @param rev_id The doc_id to save uploaded file as a revision.
		 * @see http://www.scribd.com/platform/documentation/api?method_name=docs.uploadFromUrl
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
		public function uploadFromUrl( url:String, doc_type:String=null, access:String=Access.PUBLIC, rev_id:int=0 ):void
		{
			// Let the Helper do the work to invoke the method			
			MethodGroupHelper.invokeMethod( _service, uploadFromUrl_result,
									"docs.uploadFromUrl",
									true,
									new NameValuePair( "url", url ),
									new NameValuePair( "doc_type", doc_type ),
									new NameValuePair( "access", access ),
									new NameValuePair( "rev_id", ( rev_id == 0 ? "" : rev_id.toString() ) ) );
		}
		
		/**
		 * Capture the result of the uploadFromUrl call, and dispatch
		 * the event to anyone listening.
		 *
		 * @param event The complete event generated by the URLLoader
		 * 			that was used to communicate with the Scribd API
		 *			from the invokeMethod method in MethodGroupHelper
		 */
		private function uploadFromUrl_result( event:flash.events.Event ):void
		{
			// Create a DOCS_UPLOAD_FROM_URL event
			var result:ScribdResultEvent = new ScribdResultEvent( ScribdResultEvent.DOCS_UPLOAD_FROM_URL );

			// Have the Helper handle parsing the result from the server - get the data
			// from the URLLoader which corresponds to the result from the API call
			MethodGroupHelper.processAndDispatch( _service, 
												  URLLoader( event.target ).data, 
												  result,
												  "docs_uploadFromUrl_response",
												  MethodGroupHelper.parseDocsUploadFromUrl );
		}

	}
}
